PagerDuty APIを使ってみた

#PagerDuty

#API

渋谷翔悟

2024.09.06

PagerDutyのAPI

最近PagerDuty APIを調べて実際に呼び出す検証を行う機会がありましたので、その内容をこの記事にまとめます。

pagerDutyでは700以上のプラットフォームと統合できます。もしPagerDutyとの統合に未対応なプラットフォームでもPagerDuty APIを使ってPagerDutyと連携できます。

PagerDutyのAPIの種類

PagerDutyのAPIには、「PagerDuty API」と「Event API v2」があります。

PagerDuty API
同期APIで、jiraやbacklogなどの課題管理システムとの連携では、こちらのAPIの方が適しています。このブログではPagerDuty APIの一部を紹介します。

Event API v2
非同期APIで、すぐにレスポンスが得られたり複数のリクエストも同時に捌けるので、インシデント連携時はEvent API v2の方が適しています。

ドキュメントにも、現在ではチケット管理システムとの連携には、新しい同期 Incidents API(PagerDuty API)の利用を勧める、と書いてあります。

https://developer.pagerduty.com/api-reference/YXBpOjI3NDgyNjU-pager-duty-v2-events-api#description

APIでできること

PagerDuty APIでは、PagerDutyの基本的な操作だけでなく、webから出来ることはほとんどAPIでも操作可能です。具体的には以下のようなことができます。

インシデント
- APIを使って、インシデントの一覧表示、作成、更新、確認(Acknowledge)、解決(resolve)などができます。
エスカレーションポリシー
- エスカレーションポリシーは誰にどの順で通知するかなどを設定する機能です。
- APIを使って、エスカレーションポリシーの取得、作成、更新、削除などができます。
イベントオーケストレーション
- イベントオーケストレーションでは、文字列一致などのルールに合致するイベント発生時に、指定の処理を実行することができます。
- APIを使って、イベントオーケストレーションの一覧表示、作成、更新、削除などができます。
アビリティ
- PagerDutyでは料金プランやアカウントの状態によって、利用できる機能が異なります
- APIを使って、特定のアカウントで利用可能な機能の名前を取得したり、特定の機能が利用可能であるか確認できます。
監査
- PagerDutyの監査機能では、PagerDuty上のリソースに対して操作を行った際に自動で監査レコードが生成されます。
- APIを使って、読み取り専用で証跡データを取得できます
アドオン操作
- アドオン機能では、インシデントの詳細画面に任意のUIを追加できます。
- APIを使って、アドオン機能の操作(一覧取得、インストール、更新、削除)ができます。
アラートのグループ化
- グループ化機能では、アラート内容の文字列一致、アラート発生時間、などの条件を基に、同じようなアラートをグループとしてまとめることができます。
- APIを使って、グループ化設定の一覧表示、設定作成、削除、更新などができます。
分析
- インシデントの発生から確認されるまでの平均時間や、解決までの平均時間、エスカレーション回数、通知回数など複数の分析データの取得ができます。
- APIを使って、さまざまな分析データの取得ができます。
…

残りは割愛しますが、他にも色々な機能をAPIから操作可能です。

APIキーの発行手順

PagerDuty APIとEvent API v2ではAPIキーの発行手順が異なりますが、ここで紹介するのはPagerDuty APIのAPIキーについてです。

PagerDutyのトップ画面のヘッダーから、Integrations > API Access Keysを選択して、APIキーの発行ページに移動します。Create New API Keyを押して、descriptionを入力するだけで発行できます。

pagerduty-even-api-v2-api-key

発行後はAPIキーを削除(Remove)や無効化(Disable)ができるので、利用していないAPIキーは一時的に無効化することをお勧めします。

APIを呼び出してみる

検証として以下のAPIを試してみます。

インシデント作成
ノート作成

インシデント作成

POST https://api.pagerduty.com/incidents

リクエストheader

Authorization : Token token=XXXXXXXXXXX
Accept : application/vnd.pagerduty+json;version=2
Content-Type : application/json
From: mailadress@example.com

Fromには、リクエストを行っているユーザーアカウントのメールアドレスを指定します。

リクエストbody

{
   "incident": {
    "type": "incident",
    "title": "title", // インシデントのタイトル
    "service": {
      "id": "XXXXXXX", // サービスのid
      "type": "service_reference"
    },
    "body": {
      "type": "incident_body",
      "details": "インシデントの内容"
    }
}

PagerDutyはサービスという単位で、インシデントを分けて管理を行います。

サービスIDは、APIから取得したり、PagerDutyのWeb画面から、特定のサービスを開きその時のURLパスからも取得できます。

例) https://xxx.pagerduty.com/service-directory/XXXXXXXXXX

呼び出してみると以下のようにインシデント作成できました
pagerduty-create-incident-api

実際に受け取ったレスポンスは以下です。titleなど日本語が含まれる箇所はunicodeになって返ってきました。

レスポンス

{
    "incident": {
        "incident_number": 291,
        "title": "[TEST]\u8981\u671b\u30c6\u30b9\u30c8", // インシデントのタイトル　([TEST]要望テスト)
        "description": "[TEST]\u8981\u671b\u30c6\u30b9\u30c8",
        "created_at": "2024-07-30T06:39:01Z", // 作成日時
        "updated_at": "2024-07-30T06:39:01Z", //  更新日時
        "status": "triggered", // 状態(triggered, acknowledge, resolve)
        "incident_key": "e2XXXXXXXXXXXXXXXXXXX12",
        "service": {
            "id": "PXXXXY", // service(案件)のid
            "type": "service_reference",
            "summary": "api\u691c\u8a3c\u7528", // サービス名(api検証用)
            "self": "https://api.pagerduty.com/services/PXXXXXY",
            "html_url": "https://cmcxclt.pagerduty.com/service-directory/PXXXXXY"
        },
        "assignments": [
            {
                "at": "2024-07-30T06:39:01Z",
                "assignee": { // 担当者
                    "id": "PXXXXX5", // 担当者のid
                    "type": "user_reference",
                    "summary": "Shogo Shibuya",
                    "self": "https://api.pagerduty.com/users/PXXXXX5",
                    "html_url": "https://cmcxclt.pagerduty.com/users/PXXXXX5"
                }
            }
        ],
        "assigned_via": "escalation_policy",
        "last_status_change_at": "2024-07-30T06:39:01Z",
        "resolved_at": null,
        "first_trigger_log_entry": {
            "id": "R0XXXXXXXXXXX24",
            "type": "trigger_log_entry_reference",
            "summary": "Triggered through the website.",
            "self": "https://api.pagerduty.com/log_entries/R0XXXXXXXXXXX24",
            "html_url": "https://cmcxclt.pagerduty.com/incidents/Q2XXXXXXXXXFV/log_entries/R0XXXXXXXXXXX24"
        },
        "alert_counts": {
            "all": 0,
            "triggered": 0,
            "resolved": 0
        },
        "is_mergeable": true,
        "escalation_policy": {
            "id": "PXXXXX0",
            "type": "escalation_policy_reference",
            "summary": "api\u691c\u8a3c\u7528-ep",
            "self": "https://api.pagerduty.com/escalation_policies/PXXXXX0",
            "html_url": "https://cmcxclt.pagerduty.com/escalation_policies/PXXXXX0"
        },
        "teams": [],
        "impacted_services": [
            {
                "id": "PXXXXXY",
                "type": "service_reference",
                "summary": "api\u691c\u8a3c\u7528",
                "self": "https://api.pagerduty.com/services/PXXXXXY",
                "html_url": "https://cmcxclt.pagerduty.com/service-directory/PXXXXXY"
            }
        ],
        "pending_actions": [],
        "acknowledgements": [],
        "basic_alert_grouping": null,
        "alert_grouping": null,
        "last_status_change_by": {
            "id": "PXXXXXY",
            "type": "service_reference",
            "summary": "api\u691c\u8a3c\u7528",
            "self": "https://api.pagerduty.com/services/PXXXXXY",
            "html_url": "https://cmcxclt.pagerduty.com/service-directory/PXXXXXY"
        },
        "priority": null,
        "urgency": "high",
        "id": "Q2XXXXXXXXFV",
        "type": "incident",
        "summary": "[#291] [TEST]\u8981\u671b\u30c6\u30b9\u30c8",
        "self": "https://api.pagerduty.com/incidents/Q2XXXXXXXXXFV",
        "html_url": "https://cmcxclt.pagerduty.com/incidents/Q2XXXXXXXXXFV",
        "body": {
            "details": "backlog\u306e\u8d77\u7968\u5185\u5bb9" // インシデントの内容、Custom Details(backlogの起票内容)
        }
    }
}

ノート作成

PagerDutyではインシデントに対して、ノートという形でコメントを残すことができます。

POST https://api.pagerduty.com/incidents/{id}/notes

リクエストheader

Authorization : Token token=XXXXXXXXXXX
Accept : application/vnd.pagerduty+json;version=2
Content-Type : application/json
From: mailadress@example.com

bodyパラメータ

  "note": {
    "content": "コメント"
  }

パスパラメータに、ノートを追加したいインシデントのIDが必要です。
インシデントIDは、APIから取得したり、PagerDutyのWeb画面から特定のインシデントを開きその時のURLパスからも取得できます。

例) https://cmcxclt.pagerduty.com/incidents/XXXXXXXXXX

レスポンス

{
    "note": {
        "id": "PXXXXXK",
        "user": {
            "id": "PFXXXX5",
            "type": "user_reference",
            "summary": "Shogo Shibuya",
            "self": "https://api.pagerduty.com/users/PFXXXX5",
            "html_url": "https://cmcxclt.pagerduty.com/users/PFXXXX5"
        },
        "content": "\u30b3\u30e1\u30f3\u30c8", // ノートの内容(コメント)
        "created_at": "2024-07-30T15:47:28+09:00",
        "channel": {
            "summary": "The PagerDuty website or APIs"
        }
    }
}